package wx.xml.stax.api.stream;

/**
 * This interface is used to resolve resources during an XML parse.  If an application wishes to
 * perform custom entity resolution it must register an instance of this interface with
 * the XMLInputFactory using the setXMLResolver method.
 *
 * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
 * @version 1.0
 */
public interface XMLResolver {

    /**
     * Retrieves a resource.  This resource can be of the following three return types:
     * (1) java.io.InputStream (2) wx.xml.stax.api.stream.XMLStreamReader (3) java.xml.stream.XMLEventReader.
     * If this method returns null the processor will attempt to resolve the entity using its
     * default mechanism.
     *
     * @param publicID  The public identifier of the external entity being referenced, or null if none was supplied.
     * @param systemID  The system identifier of the external entity being referenced.
     * @param baseURI   Absolute base URI associated with systemId.
     * @param namespace The namespace of the entity to resolve.
     * @return The resource requested or null.
     * @throws XMLStreamException if there was a failure attempting to resolve the resource.
     */
    public Object resolveEntity(String publicID,
                                String systemID,
                                String baseURI,
                                String namespace)
        throws XMLStreamException;
}
